﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" lasteditedby="Geert" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">Commands authentication</title>
  <keywords>
    <keyword translate="true">Authentication</keyword>
    <keyword translate="true">Commands</keyword>
    <keyword translate="true">MVVM</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Commands authentication</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">One of the questions an MVVM developer faces is how to control the executation state of a command by role or user authentication method. Catel offers an out-of-the-box solution for this problem to check the </text><text styleclass="Normal" style="font-style:italic;" translate="true">CanExecute</text><text styleclass="Normal" translate="true"> state of the commands in the UI. </text></para>
    <para styleclass="Notes"><text styleclass="Notes" translate="true">It is very important that this way of disabling commands is only used to easy the development of consistent user interfaces. It cannot replace the actual check whether a user can or cannot modify data. The actual and final responsibility still lays at the business layer.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Tagging your commands</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To know whether a specific user can execute a command, you need to be able to distinguish one command from another. The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_ICatelCommand" styleclass="Normal" style="font-style:normal;" translate="true">ICatelCommand</link><text styleclass="Normal" translate="true"> interface (which derives from </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://msdn.microsoft.com/en-us/library/system.windows.input.icommand.aspx" target="_blank" styleclass="Normal" translate="true">ICommand</link><text styleclass="Normal" translate="true">) providers a </text><link displaytype="text" defaultstyle="true" type="topiclink" href="P_Catel_MVVM_ICatelCommand_Tag" styleclass="Normal" translate="true">Tag</link><text styleclass="Normal" translate="true"> property that allows you to tag the command with any object that fits your needs. In one application, commands might be distinguished using strings, other applications use integer ID&apos;s.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">A tag must be set in the constructor of a command and cannot be changed:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Edit = </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">new</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> Command(OnEditExecute, OnEditCanExecute, &quot;editCommand&quot;);</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">IAuthenticationProvider</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_IAuthenticationProvider" styleclass="Normal" translate="true">IAuthenticationProvider</link><text styleclass="Normal" translate="true"> is a provider that needs to be implemented per application and must be registered in the IoC container. Below is the interface definition:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Interface to allow an authentication mechanism to control the CanExecute state of a command.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">interface</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> IAuthenticationProvider</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Determines whether the specified &lt;paramref name=&quot;command&quot;/&gt; can be executed. The class implementing this interface</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// can use any required method to check the command.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;para /&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// It is recommended to use the &lt;see cref=&quot;ICatelCommand.Tag&quot;/&gt; property to identify a command.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;param name=&quot;command&quot;&gt;The command that is requested.&lt;/param&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;param name=&quot;commandParameter&quot;&gt;The command parameter.&lt;/param&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;returns&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &#160; &#160;&lt;c&gt;true&lt;/c&gt; if this instance [can command be executed] the specified command; otherwise, &lt;c&gt;false&lt;/c&gt;.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/returns&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;remarks&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// The &lt;c&gt;CanExecute&lt;/c&gt; state of a command is queried a lot. The command itself does not cache any results because</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// it is not aware of role or identity changes. If caching is required, this must be implemented in the class implementing</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// the &lt;see cref=&quot;ICommandAuthenticationProvider&quot;/&gt; interface.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/remarks&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">bool</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> CanCommandBeExecuted(ICatelCommand command, </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">object</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> commandParameter);</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To register a custom implementation of the command authentication provider, use the code below:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Catel.IoC.ServiceLocator.Instance.RegisterType&lt;IAuthenticationProvider, RoleAuthenticationProvider&gt;();</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The code above registers a custom made command authentication provider that checks whether a specific role can execute the command.</text></para>
    <para styleclass="Notes"><text styleclass="Notes" translate="true">Catel checks whether an IAuthenticationProvider is registered. If not, the way commands are handled is not affected in any way. If there is an IAuthenticationProvider available, the CanExecute state is checked, even when there is no custom CanExecute implemented.</text></para>
  </body>
</topic>
